// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

package org.chromium.net;

import java.util.List;
import java.util.Map;

/**
 * Basic information about a response. Included in {@link UrlRequest.Callback} callbacks.
 * Each {@link UrlRequest.Callback#onRedirectReceived onRedirectReceived()}
 * callback gets a different copy of {@code UrlResponseInfo} describing a particular redirect
 * response.
 */
public abstract class UrlResponseInfo {
    /**
     * Unmodifiable container of response headers or trailers.
     * {@hide}.
     */
    public abstract static class HeaderBlock {
        /**
         * Returns an unmodifiable list of the response header field and value pairs.
         * The headers are in the same order they are received over the wire.
         *
         * @return an unmodifiable list of response header field and value pairs
         */
        public abstract List<Map.Entry<String, String>> getAsList();

        /**
         * Returns an unmodifiable map from response-header field names to lists of values.
         * Each list of values for a single header field is in the same order they
         * were received over the wire.
         *
         * @return an unmodifiable map from response-header field names to lists of values
         */
        public abstract Map<String, List<String>> getAsMap();
    }

    /**
     * Returns the URL the response is for. This is the URL after following
     * redirects, so it may not be the originally requested URL.
     * @return the URL the response is for.
     */
    public abstract String getUrl();

    /**
     * Returns the URL chain. The first entry is the originally requested URL;
     * the following entries are redirects followed.
     * @return the URL chain.
     */
    public abstract List<String> getUrlChain();

    /**
     * Returns the HTTP status code. When a resource is retrieved from the cache,
     * whether it was revalidated or not, the original status code is returned.
     * @return the HTTP status code.
     */
    public abstract int getHttpStatusCode();

    /**
     * Returns the HTTP status text of the status line. For example, if the
     * request received a "HTTP/1.1 200 OK" response, this method returns "OK".
     * @return the HTTP status text of the status line.
     */
    public abstract String getHttpStatusText();

    /**
     * Returns an unmodifiable list of response header field and value pairs.
     * The headers are in the same order they are received over the wire.
     * @return an unmodifiable list of response header field and value pairs.
     */
    public abstract List<Map.Entry<String, String>> getAllHeadersAsList();

    /**
     * Returns an unmodifiable map of the response-header fields and values.
     * Each list of values for a single header field is in the same order they
     * were received over the wire.
     * @return an unmodifiable map of the response-header fields and values.
     */
    public abstract Map<String, List<String>> getAllHeaders();

    /**
     * Returns {@code true} if the response came from the cache, including
     * requests that were revalidated over the network before being retrieved
     * from the cache.
     * @return {@code true} if the response came from the cache, {@code false}
     *         otherwise.
     */
    public abstract boolean wasCached();

    /**
     * Returns the protocol (for example 'quic/1+spdy/3') negotiated with the server.
     * Returns an empty string if no protocol was negotiated, the protocol is
     * not known, or when using plain HTTP or HTTPS.
     * @return the protocol negotiated with the server.
     */
    // TODO(mef): Figure out what this returns in the cached case, both with
    // and without a revalidation request.
    public abstract String getNegotiatedProtocol();

    /**
     * Returns the proxy server that was used for the request.
     * @return the proxy server that was used for the request.
     */
    public abstract String getProxyServer();

    /**
     * Returns a minimum count of bytes received from the network to process this
     * request. This count may ignore certain overheads (for example IP and TCP/UDP framing,
     * SSL handshake and framing, proxy handling). This count is taken prior to decompression
     * (for example GZIP) and includes headers and data from all redirects.
     *
     * This value may change (even for one {@link UrlResponseInfo} instance) as the request
     * progresses until completion, when {@link UrlRequest.Callback#onSucceeded onSucceeded()},
     * {@link UrlRequest.Callback#onFailed onFailed()}, or
     * {@link UrlRequest.Callback#onCanceled onCanceled()} is called.
     * @return a minimum count of bytes received from the network to process this request.
     */
    public abstract long getReceivedByteCount();
}
